FTP4W API Manual
FTP4W.DLL V.??

API MANUAL

TABLE OF CONTENTS

FTP4W.DLL provides an implementation of the FTP protocol (specified in the RFC 959) in a Windows Dynamic Library (DLL), which can be used by any language (and any compiler). It requires a Windows Sockets DLL (Winsock.DLL).

CHAPTER ONE:  LEGAL AND PERSONAL ITEMS

    1) License Agreement

    2) Special Thanks To…

    3) New Help Format Information

CHAPTER TWO:  OVERVIEW

    1) The Four Types of Functions

    2) The Two Modes of Data Transfer

    3) Do I Need an FTP Handle?

    4) Known Bugs

CHAPTER THREE:  PROGRAMMING WITH THE FTP4W API

    1) The Flow of an FTP4W Program

    2) The FTP4W API Functions


FTP4W - License Agreement
FTP4W.DLL V.??

API MANUAL

LICENSE AGREEMENT

FTP4W was written by Philippe Jounin and is Copyrighted 1994 by him and the SNCF (French Railways). The author disclaims all liability for its use or for problems, data corruption, data loss, or other loss that may result from its use.

Permission is given without restriction to use and distribute the program provided that it is distributed without charge, that it is not modified in any way, and that this file accompanies the DLL file.

This program may be included on CD-ROMs or other distribution methods freely,  provided  any  charge  for such is  for recovering the cost of distribution  and  reasonable  profit and not for the purpose of "selling" the program.  In this  case the  distribution  must  contain  the complete program including  this file.

Send any comments to ark@ifh.sncf.fr.


FTP4W - Special Thanks To…
FTP4W.DLL V.??

API MANUAL

SPECIAL THANKS TO…

Thanks To Santanu Lahiri for providing the source of WinFTP, a FTP client for windows. I have learned a lot (about FTP and Windows) by reading it.

Thanks to all the Internet community which has reported some implementation problems and has contributed to this new release, especially:

- Gillian Duncan (Corrections of this manual)

 	- Burks Oakley <b-oakley@uiuc.edu> (tests and ToolBook support)

- Richard Terpstra <terpstr2@ksla.nl> and Kees de Rooij (VB Sample)

- Vince Vielhaber <vev@msen.com> (VMS and C++ support)

- Bram Buitendijk <Bram.Buitendijk@library.KNAW.nl> (MS-Access support)

- Teemu Mottonen <Teemu.Mottonen@ktl.fi> (Corrections of this manual)

- Robin Bowes <robin@plato.ucsalf.ac.uk> (Paradox supports)

- Terry Field <terry@mincom.oz.au> (Bug report)

- David Combs <dkcombs@netcom.com> (has fully rewritten this manual)

- Andreas Tikart <Andreas.Tikart@uni-konstanz.de> (tp7 sample)

- Ricky Freyre <rickyf@mail.halcyon.com>


FTP4W - New Windows Help Format
FTP4W.DLL V.??

API MANUAL

NEW WINDOW'S BASED HELP FORMAT

A note from Michael Douglass:

Though it took me some time to complete this project, I am satisfied that I have done a good job documenting the FTP4W API Functions.  Most of the wording was taken straight from Philippe Jounin's documentation.  However, some rewording/clarification was performed on the documentation to better document the functions.

This version of the help file is still pretty much a draft version and still needs some work.  I intend to resume my Q&A sessions with Philippe to provide exact documentation for each function.  If you have a question about the FTP4W.DLL, please send me a copy as well as Philippe so that I may modify the help file to clarify any questions someone may have.  With your assistance, we can have the best documentation for the best FTP library available on the net!  My PGP public key is listed below for those security people.

THINGS TO BE COMPLETED:

    1) Not all of the functions have been rewritten.  The format seen in the first ten or so functions will be duplicated throughout the entire documentation.

THINGS TO BE ADDED:

    1) Search index

    2) Anywhere that an API function is mentioned, make it a hyperlink to the API reference for that function.

    3) Add a See Also: section to each function.  (Any advice/suggestions on how to group the functions for the See Also?)

If there are any questions or comments you wish to make on this new help file, please send them to Philippe and myself.  Thank you.

Michael Douglass

<mikedoug@texas.net>

http://www.texas.net/~mikedoug

-----BEGIN PGP PUBLIC KEY BLOCK-----

Version: 2.6.2

mQBtAzCz4n4AAAEDAK4zVDC0CpFnzy9og0Ugd5m6XjCyaAX9rHF3hAU80YO97oSM

eedS1wpDX8RqNSLQF7sMXF+78sETMG8iI1TRuGT8mB2ZnAx0j6ZXGDhBQ9bZdLMH

SEQvEsqj66KegBia7QAFEbQlTWljaGFlbCBEb3VnbGFzcyA8bWlrZWRvdWdAdGV4

YXMubmV0Pg==

=29+2

-----END PGP PUBLIC KEY BLOCK-----


FTP4W - The Four Types of Functions
FTP4W.DLL V.??

API MANUAL

THE FOUR TYPES OF FUNCTIONS

FTP4W provides four groups of functions:

Local Functions - Used for storage and use of local information

Connection functions - Used to connect and disconnect to remote locations

Data transfer functions - Used to actually transfer the data

FTP Commands functions - Other commands for ftp use


FTP4W - The Two Modes of Data Transfer
FTP4W.DLL V.??

API MANUAL

THE TWO MODES OF DATA TRANSFER

THE TWO MODES OF DATA TRANSFER FUNCTIONS:

=SYNCHRONOUS DATA TRANSFERS:

Synchronous functions have been implemented because some languages can not handle user defined messages, but it is recommended to use asynchronous versions.

If the programmer chooses the synchronous mode (set by the FtpSetSynchronousMode function), all of the FTP4W calls will return when the task is finished. Each function returns an integer return-code based on the results of the task.

=ASYNCHRONOUS DATA TRANSFERS:

Asynchronous calls give the application a way to follow the progress of a data transfer.  The DLL posts a message for the application each time it receives a packet of data.  This allows for MUCH better control of the flow of information to and from the remote host as well as allowing for an extremely better way to keep the user of your application up-to-date with the current progress of any transfer.

In the asynchronous mode (default or set by FtpSetAsynchronousMode), all data transfer functions and FtpLogin will return immediately with FTPERR_OK if the request is valid.  If the request is not valid (such as calling FtpLogin before FtpInit), then the function will return an error code to that effect (in this case, FTPERR_NOTINITIALIZED).  If the function returns FTPERR_OK, then the application must wait for a user-specified message to be posted to a user-specified window.  The extra parameters wParam and lParam of the message will be used for information such as the success or failure of the command along with any extra information (as specified in each functions definition described below).


FTP4W - FTP Handle (Like a File Handle)?
FTP4W.DLL V.??

API MANUAL

FTP HANDLE (LIKE A FILE HANDLE)?

DO I NEED AN 'FTP HANDLE' (like a file handle)?

The FTP4W calls do not need any handle to identify the FTP session. Rather, they use the Windows function GetCurrentTask to get a task identifier.  This mechanisms avoids the use of an argument but it prohibits having more than one FTP session for a given task (note that if the same application is started twice, FTP4W will just see two differents tasks, so each application can have its own FTP session).


FTP4W - Known Bugs
FTP4W.DLL V.??

API MANUAL

KNOWN BUGS

This version of Ftp4w does not support the following stacks:

- SPRY winsockets

- LAN Workplace (Novell)

To run Ftp4w with LAN Workplace, the file Ftp4w.Dll should be replaced by Ftp4wLWP.Dll.


FTP4W - The Flow of an FTP4W Application
FTP4W.DLL V.??

API MANUAL

THE FLOW OF AN FTP4W APPLICATION:

The first function that an application should call is FtpInit. It allocates buffers and gets information about the task which has called it.

If the programmer  wishes (or must) use the synchronous mode, the function FtpSetSynchronousMode must be called now.  FTP4W defaults to the asynchronouse mode, but it would be a good idea to call FtpSetAsynchronousMode explicitly to allow for future changes in FTP4W.

When the task is ready to make a connection with an FTP server. It must either

- Call FtpOpenConnection, FtpSendUserName and FtpSendPasswd

- or just call FtpLogin (which combines the 3 functions).

If it succeeds the user is logged on and can use any of the other FTP4W functions. For Instance, the application can call FtpDir to read the contents of the remote directory.

To end the connection, the application must call FtpCloseConnection. If the function does not succeed (e.g. the network has been shut down), it must call FtpLocalClose.  In both cases, to release the allocated buffers, the application must call FtpRelease before it exits.  This ending procedure can be done as follows in 'C':

if (FtpCloseConnection()!=FTPERR_OK)

     FtpLocalClose();

FtpRelease;


FTP4W - FTP4W API Functions
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTP4W API FUNCTIONS:

Ftp4wVer	Gives the 2-part version of the DLL (packed into an int).

FtpAbort	Aborts the current data transfer

FtpAppendToLocalFile	Appends a remote file onto a local file

FtpAppendToRemoteFile	Appends a local file onto a remote file

FtpBytesToBeTransferred

Gives the length of the file which is to be received

FtpBytesTransferred	Gives number of bytes which have been received

FtpCDUP	"CD's" remote default dir UP to its parent directory

FtpCloseConnection	Ends a FTP session

FtpCWD	Changes the remote default directory

FtpDataPtr	Gives a pointer to the internal Ftp4w structure

FtpDeleteFile	Deletes a remote file

FtpDir	Gets the remote directory

FtpGetFileSize	Obsolete: see instead FtpBytesToBeTransferred

FtpHelp	Gets the help file of the host's FTP server

FtpInit	First function to be called

FtpIsAsynchronousMode	Checks if Ftp4w is in asynchronous mode

FtpLocalClose	Closes local sockets

FtpLogin	Combines Ftp-OpenConnection, SendUserName, SendPasswd

FtpLogTo	Enables/Disables logs

FtpMKD	Creates a remote directory

FtpOpenConnection	Makes an FTP connection

FtpPWD	Gets the remote working directory

FtpQuote	Sends a user-defined command to the server

FtpRecvFile	Retrieves a remote file

FtpRelease	Last function to be called, frees local resources

FtpRMD	Removes a remote directory

FtpSendAccount	Sends user's account

FtpSendFile	Sends a local file to the remote host

FtpSendPasswd	Sends user's password

FtpSendUserName	Sends username

FtpSetAsynchronousMode	Switches to Asynchronous mode

FtpSetDefaultPort	Changes default FTP port

FtpSetDefaultTimeOut	Changes default time out

FtpSetNewDelay	Changes the delay between N frames

FtpSetNewSlices	Changes the above  "N frames" number

FtpSetPassiveMode	Set passive or active mode

FtpSetSynchronousMode	Switches to synchronous mode (default)

FtpSetType	Changes the data representation type

FtpSetVerboseMode	Set verbose or silent mode

FtpSyst	Asks for the host system


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTP4WVER

Syntax:	int Ftp4wVer(LPSTR szVerStr, int nStrSize)

Arguments:	LPSTR szVerStr	Buffer which is to receive the version information.  (32 bit pointer).

int nStrSize: 	Number of bytes allocated for the buffer above.

Return: 	A two byte integer containing the version number.

Ftp4wVer returns the version number of the DLL as an integer. The low order byte is the release number, and the high order byte is the major version number.

The function copies in the users's buffer a string which contains information on the DLL (name, version, author, copyright). This string is guaranteed not to exceed 100 characters.

Example:

int version = Ftp4wVer(…);

int major = (0xff00 & version) >> 4;

int release= (0x00ff & version);


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPABORT

Syntax:	int FtpAbort()

Return:

FTPERR_OK	Abort is in progress

FtpAbort aborts a data transfer without breaking the connection with the ftp server.  FtpAbort returns immediatley.  When the transfer is successfully aborted, the transfer function returns the error code (FTPERR_CANCELBYUSER) via a message to the window specified in the call to the transferring function.  Any opened file is closed but not removed.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPRECVFILE

FTPAPPENDTOLOCALFILE

Syntax:	int FtpRecvFile (LPSTR szRemote, LPSTR szLocal, char cType, BOOL bNotify, HWND hParentWnd, UINT wMsg)

int FtpAppendToLocalFile (LPSTR szRemote, LPSTR szLocal, char cType, BOOL bNotify, HWND hParentWnd, UINT wMsg)

Arguments:	LPSTR szRemote	Name of file to retrieve.  Can be either a full file name with absolute path names, or a relative filename.

LPSTR szLocal	Name of file to create locally.

char cType	Type of transfer.  Binary (TYPE_I) or ASCI (TYPE_A)

BOOL bNotify	bNotify controls whether or not your window (specified in hParentWnd) receives a message each time a frame is received.

HWND hParentWnd	This is a handle to the window that you want FTP4W to post messages to.  (See below for full details.)

UINT wMsg	Custom Message Number to send window.  (See below for full details.)

These functions copy a remote file (szRemote) to a local file (szLocal).  If the local file already exists, the function FtpRecvFile over-writes it; and FtpAppendToLocalFile appends the remote file to the end of the existing file.  If the file does not exists, it is created in either case.

Asynchronous Mode:

In the asynchronous mode, the function returns immediately.  When the transfer is completed, or interrupted for any reason, a message will be posted to the window specified by hParentWnd with the message id equal to wMsg, wParam equal to TRUE, and the lParam equal to the return code (see below for return codes).  You must specify a hParentWnd and a wMsg, or you will never know when the transfer is completed.

When using these functions in the asynchronous mode, you must still check the return code of the function.  If there is an error initiating the transfer, then the Recv functions will return immediately with the appropriate error code (see below for return values).

Synchronous Mode:

In the synchronous mode, the function returns upon completion of the transfer and does not post a message to the specified window as the asynchronous version does.  In the synchronous mode, if you set bNotify (see below) to FALSE, then you do not need to specify a hParentWnd nor do you need to specify a wMsg.  You can use "(HWND) 0, (UINT) 0" for those two parameters.

Both Asynchronous and Synchronous Modes:  (bNotify)

If you set bNotify to TRUE, then during the file transfer, the window specified by hParentWnd will receive messages with an id of wMsg,  wParam=FALSE, and lParam equal to the number of bytes transfered thus far.  In this way, you can monitor the transfer, and allow your program to alert the user of the status of the transfer.

Return Codes:

FTPERR_OK	(Synchronous) File Received

(Asynchronous) File Retrieval successfully initiated  Watch for message(s) posted to hParentWnd for further updates on the status of the transfer.

FTPERR_PASVCMDNOTIMPL	Server does not support passive mode

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_CANNOTCHANGETYPE	The server has rejected the command TYPE

FTPERR_CANTOPENFILE	Local file can not been open

FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)

FTPERR_CANTCREATESOCKET	No more free sockets (Two sockets are needed)

FTPERR_TRANSFERREFUSED	the server refused the Retrieve command

FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSENDFILE

FTPAPPENDTOREMOTEFILE

Syntax:	int FtpSendFile (LPSTR szRemote, LPSTR szLocal, char cType, BOOL bNotify, HWND hParentWnd, UINT wMsg)

int FtpAppendToRemoteFile (LPSTR szRemote, LPSTR szLocal, char cType, BOOL bNotify, HWND hParentWnd, UINT wMsg)

Arguments:	LPSTR szLocal	Name of file to send.

LPSTR szRemote	Name of file to write on the remote end.

char cType	Type of transfer.  Binary (TYPE_I) or ASCI (TYPE_A)

BOOL bNotify	bNotify controls whether or not your window (specified in hParentWnd) receives a message each time a frame is sent.

HWND hParentWnd	This is a handle to the window that you want FTP4W to post messages to.  (See below for full details.)

UINT wMsg	Custom Message Number to send window.  (See below for full details.)

These functions copy a local file (szLocal) to a remote file (szRemote).  If the local file already exists, the function FtpSendFile over-writes it; and FtpAppendToRemoteFile appends the local file to the end of the existing file.  If the file does not exists, it is created in either case.

Asynchronous Mode:

In the asynchronous mode, the function returns immediately.  When the transfer is completed, or interrupted for any reason, a message will be posted to the window specified by hParentWnd with the message id equal to wMsg, wParam equal to TRUE, and the lParam equal to the return code (see below for return codes).  You must specify a hParentWnd and a wMsg, or you will never know when the transfer is completed.

When using these functions in the asynchronous mode, you must still check the return code of the function.  If there is an error initiating the transfer, then the Send functions will return immediately with the appropriate error code (see below for return values).

Synchronous Mode:

In the synchronous mode, the function returns upon completion of the transfer and does not post a message to the specified window as the asynchronous version does.  In the synchronous mode, if you set bNotify (see below) to FALSE, then you do not need to specify a hParentWnd nor do you need to specify a wMsg.  You can use "(HWND) 0, (UINT) 0" for those two parameters.

Both Asynchronous and Synchronous Modes:  (bNotify)

If you set bNotify to TRUE, then during the file transfer, the window specified by hParentWnd will receive messages with an id of wMsg,  wParam=FALSE, and lParam equal to the number of bytes transfered thus far.  In this way, you can monitor the transfer, and allow your program to alert the user of the status of the transfer.

Return Codes:

FTPERR_OK	(Synchronous) File Sent

(Asynchronous) File Transfer successfully initiated  Watch for message(s) posted to hParentWnd for further updates on the status of the transfer.

FTPERR_PASVCMDNOTIMPL	Server does not support passive mode

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_CANNOTCHANGETYPE	The server rejects the command TYPE ASCII

FTPERR_CANTOPENFILE	Local file can not been open

FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)

FTPERR_CANTCREATESOCKET	No more free sockets (Two sockets are needed)

FTPERR_TRANSFERREFUSED	the server refused the STOR command

FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPBYTESTOBETRANSFERED

Syntax:	long FtpBytesToBeTransferred(void)

long FtpBytesToBeTransfered(void)

FtpBytesToBeTransfered returns the total length of the file which is transfered. For ASCII transfers, it can be slightly different from the number of bytes to be received. Furthermore, if the result of this function is 0, it means that the FTP server did not send this information (Windows-NT server for instance).

Note: Since the previous versions spelled Transfered instead of Transferred, the functions FtpBytesTransfered and FtpBytesTransfered are still implemented for backwards compatibilty.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPBYTESTRANSFERED

Syntax:	long FtpBytesTransferred(void)

long FtpBytesTransfered(void)

FtpBytesTransferred returns the number of bytes which has been transferred for the last initiated transfer (completed or in progress).

Note: Since the previous versions spelled Transfered instead of Transferred, the functions FtpBytesTransfered and FtpBytesTransfered are still implemented for backwards compatibilty.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPCDUP

This function changes the remote default directory up to its parent directory.

Syntax: 	FtpCDUP (void)

Return Codes:

FTPERR_OK	Directory has been changed

FTPERR_SERVERCANTEXECUTE	CWD has failed (directory does not exists..)

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPCLOSECONNECTION

Syntax:	FtpCloseConnection (void)

This function tries to gracefully close the connection. It will fail if a file transfer is in progress or if the server has timed-out. In the case of a failure to "gacefully close", you must use FtpLocalClose function.

Return Codes

FTPERR_OK	FTP session has been closed

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPCWD

Syntax:	FtpCWD (LPSTR szPath)

This function changes the current working directory on the remote server.

Argument:	LPSTR szPath	name of the new directory

Return Codes:

FTPERR_OK	Directory has been changed

FTPERR_SERVERCANTEXECUTE	CWD has failed (directory does not exists..)

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPDATAPTR

Syntax:	LPProcData FtpDataPtr (void)

FtpDataPtr returns the address of the internal structure LPProcData (see Ftp4w.h).

This function is provided only for debugging purposes and should be use cautiously.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPDELETEFILE

Syntax: FtpDeleteFile (LPSTR szFile)

Argument:	LPSTR szFile	Name of the remote file to be deleted

This function attempts to delete the remote file referenced by szFile.

Return Codes:

FTPERR_OK	File has been deleted

FTPERR_FILELOCKED	File can not be deleted

FTPERR_NOREMOTEFILE	File has not been found

FTPERR_SERVERCANTEXECUTE	File can not be deleted

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPDIR

Syntax: 	int FtpDir (LPSTR szFilter, LPSTR szFile, BOOL bLongDir, HWND hWnd, WMSG wMsg);

Arguments:	LPSTR szFilter  	Remote path and filename mask. Note that the wildcard expansion is dependent of the remote host and is not necessarily the same as MS DOS format. An empty string or NULL will give the current remote directory.

LPSTR szFile	The file where the data is to be written, if szFile is NULL, the information is posted to the window hWnd (see below)

BOOL bLongDir	Allow the application to choose between the long or the short form of listing. The short form give only the name of the files, the format of the long form depends on the server.

HWND hWnd	 	The handle of the windows to which the message is to be passed

WMSG wMsg	The application-defined message to be passed to the window.

This function retrieves a listing of a remote directory using the filter szFilter.  The listing is placed into a local file specified by szFile or posted line by line to the window specified by hWnd.

In the asynchronous mode, you can leave szFile NULL and the information will be posted to the window hWnd with the message wMsg.  The function message parameters will be wParam=FALSE each time a line of data is received. lParam is a pointer to a LPSTR containing the data. The application must save the data because the next line sent by the server will overwrite it. The string is null-terminated and contains only one line (the ending  <CR><LF> has been removed). The final message received by the application will have wParam=TRUE and lParam is the return code.

Using the asynchronous mode where szFile is NOT NULL, a message will still be posted to hWnd to let the programmer know that the transfer of the directory is complete.

In the synchronous mode, you must specify szFile, and the last two arguments are ignored completely.

Return Codes:

FTPERR_OK	Dir has been done

FTPERR_PASVCMDNOTIMPL  	Server does not support passive mode

FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_CANNOTCHANGETYPE	The server rejects the command TYPE ASCII

FTPERR_CANTOPENFILE	Local file can not been open

FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)

FTPERR_CANTCREATESOCKET       No more free sockets (Two sockets are needed)

FTPERR_TRANSFERREFUSED 	the server refused the dir command

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPGETFILESIZE

Syntax:	DWORD FtpGetFileSize(void)

Note: This function has been obsoleted by FtpBytesToBeTransferred.

This function tries to get the size of the file which is to be received. It must be used immediatly after a FtpRecvFile, because it searches in the most recent reply, looking to see if the server has sent back the size of the file.

If the function succeeds, it returns the length of the file. (Note that in ASCII mode, it can be slightly different from the number of bytes FTP4W will actually receive.) In the case of a failure it returns 0.

This function is obsolete and should be replaced by FtpBytesToBeTransferred.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPINIT

Syntax:	int FtpInit (HWND hParentWnd)

Argument:	HWND hParentWnd	The application's primary window handle.

FtpInit must be called before any other function. It allocates buffers, reads information about the task which has called it and creates an invisible window for its internal use.  Before it exits, the application must call FtpRelease to release these internal resources.

The function requires the handle of an application window (or NULL).

Return codes:

FTPERR_OK	Initialization has been done

FTPERR_INSMEMORY	Not enough memory

FTPERR_CANTCREATEWINDOW	FtpInit can't create its window

FTPERR_SESSIONUSED	The task has already called FtpInit FTP4W session


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPISASYNCHRONOUSMODE

Syntax:	BOOL FtpIsAsynchronousMode(void)

This function checks to see if Ftp4w is in the asynchronous mode.

Return:	TRUE if Ftp4w is in asynchronous mode,

FALSE if Ftp4w is in synchronous mode.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPLOCALCLOSE

Syntax:	int FtpLocalClose (void)

This function closes the opened socket without warning the server. You must use this function only if FtpCloseConnection has failed.

Return Codes:	FALSE if the session has not been initialized by FtpInit

Otherwise TRUE.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPLOGIN

Syntax:	int FtpLogin(LPSTR szHost, LPSTR szUser, LPSTR szPass, HWND hWnd, WMSG wMsg)

Arguments:	LPSTR szHost	Name of the remote host (the computer on which the server is running).

LPSTR szUser	Name of the user.

LPSTR szPass	Password (it can be NULL if the user has no password).

HWND hWnd	Is the handler of the windows to which the message is to be posted.

WMSG wMsg	Is the application-defined message to be posted to the application.

This function combines the three functions FtpOpenConnection, FtpSendUserName and FtpSendPasswd. In the synchronous mode, FtpLogin will return when the login process is complete, or when there is an error; and the two last arguments are unused. In the asyncrhonous mode FtpLogin will immediately return FTPERR_OK, and when the login process is complete, or when there is an error, the application will receive a wMsg message in the hWnd window.

The message will include the parametersby:

wParam: always TRUE

lParam: The return code of the function

Return Codes:

Return codes are in the Low Word of the lParam argument:

FTPERR_OK	User is logged on

FTPERR_ENTERACCOUNT	Successful function but server awaits an account name

FTPERR_LOGINREFUSED	The USER/PASSWD has been rejected

FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.

FTPERR_CANTCREATESOCKET 	The socket has not been created

FTPERR_CONNECTREJECTED 	Connect has been rejected (server is not a FTP server, ...)

FTPERR_CANTCONNECT	The connect has failed

FTPERR_TIMEOUT 	The connect has timed-out


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPLOGTO

Syntax:	int FtpLogTo (HFILE hLogFile)

Argument: 	HFILE hLogFile	A opened file handler to be written to.  (pass it HFILE_ERROR to set silent mode.)

This function set or reset a log mode. In log mode, all data sent or received on the control port (21) are sent to the opened file passed as an argument.  The frame which contains the password is logged as "PASS +++" for obvious reasons.

To set silent mode (default), just call FtpLogTo (HFILE_ERROR).  Note that the file is not closed by Ftp4w.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPMKD

This function creates a directory on the remote server. The full name of the new directory is returned in a user's buffer. If the FTP-server has succesfully created the directory but did not return its full name, this buffer is set to an empty string.

Syntax: FtpMKD (LPSTR szPath, LPSTR szBuf, UINT uBufSize)

Argument: 	szPath: 	name of the directory to be created

szBuf:	Buffer to be filled with the full name of the created directory

uBufSize: 	Size of the user's buffer

Return Codes:

FTPERR_OK	Directory has been created

FTPERR_SERVERCANTEXECUTE	MKD has failed (can not create directory, directory already exists, ...)

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPOPENCONNECTION

This function establishes the connection with the FTP server.

Once the connection is done, it waits for the reply of the server.

This reply must begin with "220" (RFC 959), if not a special error is generated.

FTP4W does not check to see if a connection already exists.

Syntax: FtpOpenConnection (LPSTR szHost)

Argument: szHost: The name of the remote host to connect to

Return codes:

FTPERR_OK	Successful connection

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_CANTCREATESOCKET 	The socket has not been created

FTPERR_CONNECTREJECTED 	Connection has been rejected (server is not a FTP server, ...)

FTPERR_CANTCONNECT	The connection has failed

FTPERR_TIMEOUT 	The connection has timed-out

FTPERR_NOREPLY 	The connection is successful, but FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	The connection is successful and FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPPWD

This function returns the name of the default directory on the remote server.

Syntax: FtpPWD (LPSTR szPath, UINT uBufSize)

Argument: 	szPath: 	buffer to be filled with the name of the remote default directory

uBufSize:	size of this buffer

Return Codes:

FTPERR_OK	Name of the remote directory available in the buffer

FTPERR_SERVERCANTEXECUTE	PWD has failed (directory does not exists..)

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_PWDBADFMT 	FTP4W can not interpret server's answer

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPQUOTE

It allows the user to send to the server any FTP command he wants. FTP4W will send it to the server and waits for its reply.

Note:  The names of the commands given there are DIFFERENT from the commands you would type in by hand with a text-oriented FTP client. In fact, the ones you type in by hand are read by a higher-level "front end" to the REAL ftp, and that higher-level then translates them into shorter names.

To have the list of the codes accepted by the FTP servers, refers to the RFC 959.

Note: The application can not start a data-transfer with this command.

The return code is either a FTP code (ie 200) or a FTP4W error code (FTPERR_NOREPLY, FTPERR_SENDREFUSED, ...).

If szReplyBuf is not NULL, The reply (if any) is copied into a user's buffer.

Syntax FtpQuote (LPSTR szCmd, LPSTR szReplyBuf, UINT uBufSize);

Arguments:	szCmd	The command to be sent

szReplyBuf	The buffer to copy the answer

uBufSize	The size of the user's buffer

Return Codes: 	A Ftp4w's error code

or a 3 digits number between 100 and 699.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPRECVFILE

Note : Since FtpAppendToLocalFile uses exactly the same syntax, only FtpRecvFile will be described.  The only difference between them occurs when the local file already exists, in which case the Append function appends the remote file onto it, whereas the Recv function simply over-writes it.

This function copies a remote file to a local file. In the asynchronous mode, the function returns immediatly, then the application will receive a message when the transfer is completed with wParam=TRUE (transfer completed), lParam=return code. In the synchronous mode, the function returns when the transfer is completed.

In the notification mode, the application will receive a message each time some data has been received. The same message as above is used but wParam will be FALSE, lParam will be the current position in the file (it is also the number of bytes which have been received).

In synchronous mode, if bNotify has not been set, the final arguments hParentWnd and wMsg are not used.

If the local file already exists, The function FtpRecvFile over-writes it, whereas FtpAppendToLocalFile appends the remote file at the end of the file.

If the file does not exists, it is created in any case.

Syntax:

FtpRecvFile (LPSTR szRemote, LPSTR szLocal,

                    char cType, BOOL bNotify,

                    HWND hParentWnd, UINT wMsg)

FtpAppendToLocalFile (LPSTR szRemote, LPSTR szLocal,

                    	              char cType, BOOL bNotify,

                                  HWND hParentWnd, UINT wMsg)

Arguments: 	szRemote  	Remote file specification

szLocal	The file where to write the data.

cType	TYPE_A for ASCII, TYPE_B for binary

bNotify	A message should be sent by to the application each time a frame

has been received.

hWnd 	the handler of the windows to which the message is to be passed

wMsg 	the application-defined message to be passed to the application

Return Codes:

FTPERR_OK	File received

FTPERR_PASVCMDNOTIMPL  	Server does not support passive mode

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_CANNOTCHANGETYPE	The server has rejected the command TYPE

FTPERR_CANTOPENFILE	Local file can not been open

FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)

FTPERR_CANTCREATESOCKET       No more free sockets (Two sockets are needed)

FTPERR_TRANSFERREFUSED 	the server refused the Retrieve command

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPRELEASE

FtpRelease must be called before the application exits. It frees all resources taken by FtpInit.

The function requires no arguments.

Syntax:  FtpRelease ()

return codes:

FTPERR_OK	Resources have been released

FTPERR_STILLCONNECTED	The connection is still active. Nothing has been done.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPRESTART

This command makes the server to begin the next file transfer at the specified position. This command should be issued just prior a file transfer request, which is not possible with the high-level transfer functions. Therefore this is mostly an internal command.

It has been exported since some servers does not support this command. Thus it is an easy way to check the server before starting any file transfer.

Syntax:  FtpRestart (long lByteTransfer)

Argument : 	lByteTransfer 	Position of the next file transfer. If this value is negative or 0,

the function does nothing and returns FTPERR_RESTARTOK

return codes:

FTPERR_RESTARTOK	The command successful but it has no effect.

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection

FTPERR_CMDNOTIMPLEMENTED	Command not implemented


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPRESTARTRECVFILE

This command starts a file transfer from a specified position. Please refer to the FtpRecvFile command to have more info concerning file transfers.

This command should be used only in binary mode, since the position in a text file has little meaning.

Syntax:  FtpRestartRecvFile	(LPSTR szRemote, HFILE hLocal, char cType,

     	 BOOL bNotify, long lByteCount,

                    	      HWND hParentWnd, UINT wMsg);

Arguments :	szRemote	The remote file to be received

hLocal	A Windows handler to an opened file which is to be written

cType	TYPE_A for ASCII, TYPE_B for binary

bNotify	A message should be sent by to the application each time a frame

has been received.

lByteCount	Starting position of the transfer

hWnd 	the handler of the windows to which to pass the message

wMsg 	the application-defined message to pass to the application

Syntax:  FtpRestartSendFile	(HFILE hLocal, LPSTR szRemote, char cType,

     	 BOOL bNotify, long lByteCount,

                    	      HWND hParentWnd, UINT wMsg);

Return Codes:

FTPERR_OK	File received

FTPERR_PASVCMDNOTIMPL  	Server does not support passive mode

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_CANNOTCHANGETYPE	The server has rejected the command TYPE

FTPERR_CANTOPENFILE	Local file can not been open

FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)

FTPERR_CANTCREATESOCKET       No more free sockets (Two sockets are needed)

FTPERR_TRANSFERREFUSED 	the server refused the Retrieve command

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPRESTARTSENDFILE

This command starts a file transfer from a specified position. Please refer to the FtpSendFile command to have more info concerning file transfers.

This command should be used only in binary mode, since the position in a text file has little meaning.

Syntax:  FtpRestartSendFile	(HFILE hLocal, LPSTR szRemote, char cType,

     	 BOOL bNotify, long lByteCount,

                    	      HWND hParentWnd, UINT wMsg);

Arguments :	hLocal	A Windows handler to an opened file which is to be read. Ftp4w 	starts reading this file from the current position.

szRemote	The remote file to be written from the position lByteCount.

cType	TYPE_A for ASCII, TYPE_B for binary

bNotify	A message should be sent by to the application each time a frame

has been received.

lByteCount	Starting position of the transfer

hWnd 	the handler of the windows to which to pass the message

wMsg 	the application-defined message to pass to the application

Syntax:  FtpRestartSendFile	(HFILE hLocal, LPSTR szRemote, char cType,

     	 BOOL bNotify, long lByteCount,

                    	      HWND hParentWnd, UINT wMsg);

Return Codes:

FTPERR_OK	File has been sent

FTPERR_PASVCMDNOTIMPL  	Server does not support passive mode

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_CANNOTCHANGETYPE	The server rejects the command TYPE ASCII

FTPERR_CANTOPENFILE	Local file can not been open

FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)

FTPERR_CANTCREATESOCKET       No more free sockets (Two sockets are needed)

FTPERR_TRANSFERREFUSED 	the server refused the STOR command

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPRMD

This function removes a directory from the remote server.

Syntax: FtpRMD (LPSTR szPath)

Argument: 	szPath: name of the directory to be deleted

Return Codes:

FTPERR_OK	Directory has been removed

FTPERR_SERVERCANTEXECUTE	RMD has failed (directory is not empty)

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSENDACCOUNT

This function sends the account to the server.  This function should be used when FtpLogin or FtpSendPasswd return FTP_ENTERACCOUNT.

Syntax: FtpSendAccount (LPSTR szAccount)

Argument: szAccount: Account information

Return Codes:

FTPERR_OK	User is logged on

FTPERR_LOGINREFUSED	The USER/PASSWD/ACCOUNT has been rejected

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSENDFILE

Note : Since FtpAppendToRemoteFile uses exactly the same syntax, only FtpSendFile will be described.  The only difference between them occurs when the remote already exists, in which case the Append function appends the local file onto it, whereas the Send function simply over-writes it.

This function copies a local file to a remote file.

The application will receive a message when the transfer is completed with wParam=TRUE (transfer completed), lParam=return code. In the synchronous mode, the function returns only after the transfer has been completed.

In the notification mode, the application will receive a message each time some data has been sent. The same message as above is used but wParam will be FALSE, lParam will be the current position in the file (it is also the number of bytes which have been sent).

In synchronous mode, if bNotify has not been set, the final arguments (hParentWnd and wMsg) are not used.

Syntax:

FtpSendFile (LPSTR szLocal, LPSTR szRemote,

                    char cType, BOOL bNotify,

                    HWND hParentWnd, UINT wMsg)

FtpAppendToRemoteFile (LPSTR szLocal, LPSTR szRemote,

                    	char cType, BOOL bNotify,

                    	HWND hParentWnd, UINT wMsg)

Arguments:	 szLocal	The file to be sent

szRemote  	Remote file specification

cType	TYPE_A for ASCII, TYPE_B for binary

bNotify	A message should be sent by to the application each time a frame

has been received.

hWnd 	the handler of the windows to which to pass the message

wMsg 	the application-defined message to pass to the application

Return Codes:

FTPERR_OK	File has been sent

FTPERR_PASVCMDNOTIMPL  	Server does not support passive mode

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_CANNOTCHANGETYPE	The server rejects the command TYPE ASCII

FTPERR_CANTOPENFILE	Local file can not been open

FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)

FTPERR_CANTCREATESOCKET       No more free sockets (Two sockets are needed)

FTPERR_TRANSFERREFUSED 	the server refused the STOR command

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSENDPASSWD

This function sends the password to the server.

Syntax: FtpSendPasswd (LPSTR szPasswd)

Argument: szPasswd: Password of the user

Return Codes:

FTPERR_OK	User is logged on

FTPERR_ENTERACCOUNT	Successful function but server awaits an account name.

FTPERR_LOGINREFUSED	The USER/PASSWD has been rejected

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSENDUSERNAME

This function sends the user's name to the server. This authentification is necessary to begin a file transfer.

This function will usually return the "error-like" return value: FTPERR_ENTERPASSWORD (Successful function but server awaits a password). It means only that everything is just fine, it is simply reminding them that it still needs the password.>

Syntax: FtpSendUserName (LPSTR szUserName)

Argument: szUserName: Name of the user

Return Codes:

FTPERR_OK	User is logged on

FTPERR_ENTERPASSWORD	Successful function but server awaits a password.

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSETDEFAULTPORT

FTPSETDEFAULTTIMEOUT

Syntax:

int FtpSetDefaultPort (int nDefPort)

int FtpSetDefaultTimeOut (int nTimeOutInSeconds)

These functions are used to change either the FTP-control port (21 by default) or the timeout (30 seconds by default).

Note that the FTP-data potr can not be changed.

The new timeout is given in seconds.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSETNEWDELAY

FTPSETNEWSLICES

Syntax:

int  FtpSetNewDelay  (int nNewDelayInMilliseconds)

int  FtpSetNewSlices (int nSliceAlone, int nSliceMultiUser)

When a given number of frames has been received during a data transfer, FTP4W will wait for a while in order to let other tasks run.

FtpSetNewDelay allows the application to change the length of the pause. The argument is the length of the pause to be applied in milliseconds.

FtpSetNewSlices is used to change the number of frames which will cause a pause. The first argument is the number of frames when one FTP session are active, the second argument is used when two or more sessions are active.

Both arguments should not be set to zero.


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSETPASSIVEMODE

Syntax:

void FtpSetPassiveMode (BOOL bPassif)

These command requests the FTP-server to "listen" on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command.

These command is not implemented on all FTP-server, and thus the application must check the return code of the next data-transfer (FtpRecvFile, FtpSendFile, FtpDir).

Note: If FtpInit has not been called, these calls will cause a GPF.

Arguments:	bPassif	TRUE if the application wants to switch to passive

mode, FALSE if it wants to reset the default mode.

Return codes:

FTPERR_OK	Mode has been changed


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSETTYPE

This function changes the default transfer type.

Syntax: FtpSetType (char cType)

Argument: 	cType: new default transfer mode (either TYPE_A or TYPE_I)

Return Codes:

FTPERR_OK	Type has been changed

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSETVERBOSEMODE

If a programmer needs to have a look on each frame sent by the server, he uses this function. He will get a message (by the SendMessage function) each time a frame has been received. The argument wParam is TRUE, lParam points to the frame. It is NULL-terminated but can contain p more than one line (a line is ended with <CR><LF>).

Note that the frame will be overwritten by the next reply from the server.

Syntax: FtpSetVerboseMode (BOOL bVerboseMode, WND hWnd, WMSG wMsg)

Arguments:	bVerboseMode TRUE if the application wants to watch incoming messages,

FALSE to end a previous FtpSetVerboseMode

hWnd	the handler of the window to which the message is to be passed

wMsg 	the application-defined message to be passed to the application each time a frame has been received.

Return codes

FTPERR_OK	Mode has been changed

FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit


FTP4W - API Function Reference
FTP4W.DLL V.??

API FUNCTION REFERENCE

FTPSYST

This command asks to the server the system on which it is running.

The return code is either a FTP4W error code (FTPERR_NOREPLY, FTPERR_SENDREFUSED, ...). or the index into the array of strings passed as an argument.

The argument given is an array of pointers to string. Each string should contain a possible system name. The final pointer must be NULL The function returns the index of the string whose contents matches the answer returned by the server. If no system name has been found, FTPERR_SYSTUNKNOWN is returned.

In the given strings, upper and lower case characters are to be treated identically.

Since the position of the system's name in the host's answer is unknown, it can not be returned in a buffer. If the application wants to have the full host's answer, it must either use the verbose mode (FtpsetVerboseMode) or use the FtpQuote command.

Syntax FtpSyst (LPSTR FAR *szSystStr)

Arguments:	szSystStr	An array of strings that contains the system names to be checked.

Return Codes:

The index of the array of strings

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit

FTPERR_SYSTUNKNOWN	The server has returned a string, but its answer does not match with the array of strings given as argument.

FTPERR_NOTCONNECTED 	User is not connected to a remote host

FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)

FTPERR_NOREPLY 	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).

FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection

Example:

static char *szSystem[] = { "Unix", "VMS", "Dos", NULL };

Rc=FtpSyst (szSystem);

printf ("System %s", Rc==FTPERR_SYSTUNKNOWN ? "Unknown": szSystem[Rc]);